IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3/perl5/Getopt::Long.z/Getopt::Long

Text File | 2002-10-03 | 27.5 KB | 727 lines

GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))                                                GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))



NNNNAAAAMMMMEEEE
     GetOptions - extended processing of command line options

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
       use Getopt::Long;
       $result = GetOptions (...option-descriptions...);


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     The Getopt::Long module implements an extended getopt function called
     _G_e_t_O_p_t_i_o_n_s(). This function adheres to the POSIX syntax for command line
     options, with GNU extensions. In general, this means that options have
     long names instead of single letters, and are introduced with a double
     dash "--". Support for bundling of command line options, as was the case
     with the more traditional single-letter approach, is provided but not
     enabled by default. For example, the UNIX "ps" command can be given the
     command line "option"

       -vax

     which means the combination of ----vvvv, ----aaaa and ----xxxx. With the new syntax --------vvvvaaaaxxxx
     would be a single option, probably indicating a computer architecture.

     Command line options can be used to set values. These values can be
     specified in one of two ways:

       --size 24
       --size=24

     GetOptions is called with a list of option-descriptions, each of which
     consists of two elements: the option specifier and the option linkage.
     The option specifier defines the name of the option and, optionally, the
     value it can take. The option linkage is usually a reference to a
     variable that will be set when the option is used. For example, the
     following call to GetOptions:

       GetOptions("size=i" => \$offset);

     will accept a command line option "size" that must have an integer value.
     With a command line of "--size 24" this will cause the variable $offset
     to get the value 24.

     Alternatively, the first argument to GetOptions may be a reference to a
     HASH describing the linkage for the options, or an object whose class is
     based on a HASH. The following call is equivalent to the example above:

       %optctl = ("size" => \$offset);
       GetOptions(\%optctl, "size=i");

     Linkage may be specified using either of the above methods, or both.
     Linkage specified in the argument list takes precedence over the linkage
     specified in the HASH.



                                                                        PPPPaaaaggggeeee 1111






GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))                                                GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))



     The command line options are taken from array @ARGV. Upon completion of
     GetOptions, @ARGV will contain the rest (i.e. the non-options) of the
     command line.

     Each option specifier designates the name of the option, optionally
     followed by an argument specifier.

     Options that do not take arguments will have no argument specifier. The
     option variable will be set to 1 if the option is used.

     For the other options, the values for argument specifiers are:

     !       Option does not take an argument and may be negated, i.e.
             prefixed by "no". E.g. "foo!" will allow --------ffffoooooooo (with value 1) and
             ----nnnnooooffffoooooooo (with value 0).  The option variable will be set to 1, or
             0 if negated.

     +       Option does not take an argument and will be incremented by 1
             every time it appears on the command line. E.g. "more+", when
             used with --------mmmmoooorrrreeee --------mmmmoooorrrreeee --------mmmmoooorrrreeee, will set the option variable to 3
             (provided it was 0 or undefined at first).

             The ++++ specifier is ignored if the option destination is not a
             SCALAR.

     =s      Option takes a mandatory string argument.  This string will be
             assigned to the option variable.  Note that even if the string
             argument starts with ---- or --------, it will not be considered an option
             on itself.

     :s      Option takes an optional string argument.  This string will be
             assigned to the option variable.  If omitted, it will be assigned
             "" (an empty string).  If the string argument starts with ---- or
             --------, it will be considered an option on itself.

     =i      Option takes a mandatory integer argument.  This value will be
             assigned to the option variable.  Note that the value may start
             with ---- to indicate a negative value.

     :i      Option takes an optional integer argument.  This value will be
             assigned to the option variable.  If omitted, the value 0 will be
             assigned.  Note that the value may start with ---- to indicate a
             negative value.

     =f      Option takes a mandatory real number argument.  This value will
             be assigned to the option variable.  Note that the value may
             start with ---- to indicate a negative value.

     :f      Option takes an optional real number argument.  This value will
             be assigned to the option variable.  If omitted, the value 0 will
             be assigned.




                                                                        PPPPaaaaggggeeee 2222






GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))                                                GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))



     A lone dash ---- is considered an option, the corresponding option name is
     the empty string.

     A double dash on itself -------- signals end of the options list.

     LLLLiiiinnnnkkkkaaaaggggeeee ssssppppeeeecccciiiiffffiiiiccccaaaattttiiiioooonnnn

     The linkage specifier is optional. If no linkage is explicitly specified
     but a ref HASH is passed, GetOptions will place the value in the HASH.
     For example:

       %optctl = ();
       GetOptions (\%optctl, "size=i");

     will perform the equivalent of the assignment

       $optctl{"size"} = 24;

     For array options, a reference to an array is used, e.g.:

       %optctl = ();
       GetOptions (\%optctl, "sizes=i@");

     with command line "-sizes 24 -sizes 48" will perform the equivalent of
     the assignment

       $optctl{"sizes"} = [24, 48];

     For hash options (an option whose argument looks like "name=value"), a
     reference to a hash is used, e.g.:

       %optctl = ();
       GetOptions (\%optctl, "define=s%");

     with command line "--define foo=hello --define bar=world" will perform
     the equivalent of the assignment

       $optctl{"define"} = {foo=>'hello', bar=>'world')

     If no linkage is explicitly specified and no ref HASH is passed,
     GetOptions will put the value in a global variable named after the
     option, prefixed by "opt_". To yield a usable Perl variable, characters
     that are not part of the syntax for variables are translated to
     underscores. For example, "--fpp-struct-return" will set the variable
     $opt_fpp_struct_return. Note that this variable resides in the namespace
     of the calling program, not necessarily mmmmaaaaiiiinnnn.  For example:

       GetOptions ("size=i", "sizes=i@");

     with command line "-size 10 -sizes 24 -sizes 48" will perform the
     equivalent of the assignments




                                                                        PPPPaaaaggggeeee 3333






GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))                                                GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))



       $opt_size = 10;
       @opt_sizes = (24, 48);

     A lone dash ---- is considered an option, the corresponding Perl identifier
     is $opt_ .

     The linkage specifier can be a reference to a scalar, a reference to an
     array, a reference to a hash or a reference to a subroutine.

     Note that, if your code is running under the recommended use strict
     'vars' pragma, it may be helpful to declare these package variables via
     use vars perhaps something like this:

       use vars qw/ $opt_size @opt_sizes $opt_bar /;

     If a REF SCALAR is supplied, the new value is stored in the referenced
     variable. If the option occurs more than once, the previous value is
     overwritten.

     If a REF ARRAY is supplied, the new value is appended (pushed) to the
     referenced array.

     If a REF HASH is supplied, the option value should look like "key" or
     "key=value" (if the "=value" is omitted then a value of 1 is implied).
     In this case, the element of the referenced hash with the key "key" is
     assigned "value".

     If a REF CODE is supplied, the referenced subroutine is called with two
     arguments: the option name and the option value.  The option name is
     always the true name, not an abbreviation or alias.

     AAAAlllliiiiaaaasssseeeessss aaaannnndddd aaaabbbbbbbbrrrreeeevvvviiiiaaaattttiiiioooonnnnssss

     The option name may actually be a list of option names, separated by
     "|"s, e.g. "foo|bar|blech=s". In this example, "foo" is the true name of
     this option. If no linkage is specified, options "foo", "bar" and "blech"
     all will set $opt_foo. For convenience, the single character "?" is
     allowed as an alias, e.g. "help|?".

     Option names may be abbreviated to uniqueness, depending on configuration
     option aaaauuuuttttoooo____aaaabbbbbbbbrrrreeeevvvv.

     NNNNoooonnnn----ooooppppttttiiiioooonnnn ccccaaaallllllll----bbbbaaaacccckkkk rrrroooouuuuttttiiiinnnneeee

     A special option specifier, <>, can be used to designate a subroutine to
     handle non-option arguments. GetOptions will immediately call this
     subroutine for every non-option it encounters in the options list.  This
     subroutine gets the name of the non-option passed.  This feature requires
     configuration option ppppeeeerrrrmmmmuuuutttteeee, see section CONFIGURATION OPTIONS.






                                                                        PPPPaaaaggggeeee 4444






GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))                                                GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))



     See also the examples.

     OOOOppppttttiiiioooonnnn ssssttttaaaarrrrtttteeeerrrrssss

     On the command line, options can start with ---- (traditional), -------- (POSIX)
     and ++++ (GNU, now being phased out). The latter is not allowed if the
     environment variable PPPPOOOOSSSSIIIIXXXXLLLLYYYY____CCCCOOOORRRRRRRREEEECCCCTTTT has been defined.

     Options that start with "--" may have an argument appended, separated
     with an "=", e.g. "--foo=bar".

     RRRReeeettttuuuurrrrnnnn vvvvaaaalllluuuueeeessss aaaannnndddd EEEErrrrrrrroooorrrrssss

     Configuration errors and errors in the option definitions are signalled
     using die() and will terminate the calling program unless the call to
     Getopt::Long::GetOptions() was embedded in eval { ... } or die() was
     trapped using $SIG{__DIE__}.

     A return value of 1 (true) indicates success.

     A return status of 0 (false) indicates that the function detected one or
     more errors during option parsing. These errors are signalled using
     warn() and can be trapped with $SIG{__WARN__}.

     Errors that can't happen are signalled using Carp::croak().

CCCCOOOOMMMMPPPPAAAATTTTIIIIBBBBIIIILLLLIIIITTTTYYYY
     _G_e_t_o_p_t::_L_o_n_g::_G_e_t_O_p_t_i_o_n_s() is the successor of nnnneeeewwwwggggeeeettttoooopppptttt....ppppllll that came
     with Perl 4. It is fully upward compatible.  In fact, the Perl 5 version
     of newgetopt.pl is just a wrapper around the module.

     If an "@" sign is appended to the argument specifier, the option is
     treated as an array. _V_a_l_u_e(s) are not set, but pushed into array
     @opt_name. If explicit linkage is supplied, this must be a reference to
     an ARRAY.

     If an "%" sign is appended to the argument specifier, the option is
     treated as a hash. _V_a_l_u_e(s) of the form "name=value" are set by setting
     the element of the hash %opt_name with key "name" to "value" (if the
     "=value" portion is omitted it defaults to 1). If explicit linkage is
     supplied, this must be a reference to a HASH.

     If configuration option ggggeeeettttoooopppptttt____ccccoooommmmppppaaaatttt is set (see section CONFIGURATION
     OPTIONS), options that start with "+" or "-" may also include their
     arguments, e.g. "+foo=bar". This is for compatiblity with older
     implementations of the GNU "getopt" routine.

     If the first argument to GetOptions is a string consisting of only non-
     alphanumeric characters, it is taken to specify the option starter
     characters. Everything starting with one of these characters from the
     starter will be considered an option. UUUUssssiiiinnnngggg aaaa ssssttttaaaarrrrtttteeeerrrr aaaarrrrgggguuuummmmeeeennnntttt iiiissss
     ssssttttrrrroooonnnnggggllllyyyy ddddeeeepppprrrreeeeccccaaaatttteeeedddd....



                                                                        PPPPaaaaggggeeee 5555






GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))                                                GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))



     For convenience, option specifiers may have a leading ---- or --------, so it is
     possible to write:

        GetOptions qw(-foo=s --bar=i --ar=s);


EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
     If the option specifier is "one:i" (i.e. takes an optional integer
     argument), then the following situations are handled:

        -one -two            -> $opt_one = '', -two is next option
        -one -2              -> $opt_one = -2

     Also, assume specifiers "foo=s" and "bar:s" :

        -bar -xxx            -> $opt_bar = '', '-xxx' is next option
        -foo -bar            -> $opt_foo = '-bar'
        -foo --              -> $opt_foo = '--'

     In GNU or POSIX format, option names and values can be combined:

        +foo=blech           -> $opt_foo = 'blech'
        --bar=               -> $opt_bar = ''
        --bar=--             -> $opt_bar = '--'

     Example of using variable references:

        $ret = GetOptions ('foo=s', \$foo, 'bar=i', 'ar=s', \@ar);

     With command line options "-foo blech -bar 24 -ar xx -ar yy" this will
     result in:

        $foo = 'blech'
        $opt_bar = 24
        @ar = ('xx','yy')

     Example of using the <> option specifier:

        @ARGV = qw(-foo 1 bar -foo 2 blech);
        GetOptions("foo=i", \$myfoo, "<>", \&mysub);

     Results:

        mysub("bar") will be called (with $myfoo being 1)
        mysub("blech") will be called (with $myfoo being 2)

     Compare this with:

        @ARGV = qw(-foo 1 bar -foo 2 blech);
        GetOptions("foo=i", \$myfoo);

     This will leave the non-options in @ARGV:



                                                                        PPPPaaaaggggeeee 6666






GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))                                                GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))



        $myfoo -> 2
        @ARGV -> qw(bar blech)


CCCCOOOONNNNFFFFIIIIGGGGUUUURRRRAAAATTTTIIIIOOOONNNN OOOOPPPPTTTTIIIIOOOONNNNSSSS
     GGGGeeeettttOOOOppppttttiiiioooonnnnssss can be configured by calling subroutine
     GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg::::::::CCCCoooonnnnffffiiiigggguuuurrrreeee. This subroutine takes a list of quoted strings,
     each specifying a configuration option to be set, e.g.  iiiiggggnnnnoooorrrreeee____ccccaaaasssseeee.
     Options can be reset by prefixing with nnnnoooo____, e.g.  nnnnoooo____iiiiggggnnnnoooorrrreeee____ccccaaaasssseeee. Case
     does not matter. Multiple calls to ccccoooonnnnffffiiiigggg are possible.

     Previous versions of Getopt::Long used variables for the purpose of
     configuring. Although manipulating these variables still work, it is
     strongly encouraged to use the new ccccoooonnnnffffiiiigggg routine. Besides, it is much
     easier.

     The following options are available:

     default     This option causes all configuration options to be reset to
                 their default values.

     auto_abbrev Allow option names to be abbreviated to uniqueness.  Default
                 is set unless environment variable POSIXLY_CORRECT has been
                 set, in which case aaaauuuuttttoooo____aaaabbbbbbbbrrrreeeevvvv is reset.

     getopt_compat
                 Allow '+' to start options.  Default is set unless
                 environment variable POSIXLY_CORRECT has been set, in which
                 case ggggeeeettttoooopppptttt____ccccoooommmmppppaaaatttt is reset.

     require_order
                 Whether non-options are allowed to be mixed with options.
                 Default is set unless environment variable POSIXLY_CORRECT
                 has been set, in which case b<require_order> is reset.

                 See also ppppeeeerrrrmmmmuuuutttteeee, which is the opposite of rrrreeeeqqqquuuuiiiirrrreeee____oooorrrrddddeeeerrrr.

     permute     Whether non-options are allowed to be mixed with options.
                 Default is set unless environment variable POSIXLY_CORRECT
                 has been set, in which case ppppeeeerrrrmmmmuuuutttteeee is reset.  Note that
                 ppppeeeerrrrmmmmuuuutttteeee is the opposite of rrrreeeeqqqquuuuiiiirrrreeee____oooorrrrddddeeeerrrr.

                 If ppppeeeerrrrmmmmuuuutttteeee is set, this means that

                     -foo arg1 -bar arg2 arg3

                 is equivalent to

                     -foo -bar arg1 arg2 arg3

                 If a non-option call-back routine is specified, @ARGV will
                 always be empty upon succesful return of GetOptions since all



                                                                        PPPPaaaaggggeeee 7777






GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))                                                GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))



                 options have been processed, except when -------- is used:

                     -foo arg1 -bar arg2 -- arg3

                 will call the call-back routine for arg1 and arg2, and
                 terminate leaving arg2 in @ARGV.

                 If rrrreeeeqqqquuuuiiiirrrreeee____oooorrrrddddeeeerrrr is set, options processing terminates when
                 the first non-option is encountered.

                     -foo arg1 -bar arg2 arg3

                 is equivalent to

                     -foo -- arg1 -bar arg2 arg3


     bundling (default: reset)
                 Setting this variable to a non-zero value will allow single-
                 character options to be bundled. To distinguish bundles from
                 long option names, long options must be introduced with --------
                 and single-character options (and bundles) with ----. For
                 example,

                     ps -vax --vax

                 would be equivalent to

                     ps -v -a -x --vax

                 provided "vax", "v", "a" and "x" have been defined to be
                 valid options.

                 Bundled options can also include a value in the bundle; for
                 strings this value is the rest of the bundle, but integer and
                 floating values may be combined in the bundle, e.g.

                     scale -h24w80

                 is equivalent to

                     scale -h 24 -w 80

                 Note: resetting bbbbuuuunnnnddddlllliiiinnnngggg also resets bbbbuuuunnnnddddlllliiiinnnngggg____oooovvvveeeerrrrrrrriiiiddddeeee.

     bundling_override (default: reset)
                 If bbbbuuuunnnnddddlllliiiinnnngggg____oooovvvveeeerrrrrrrriiiiddddeeee is set, bundling is enabled as with
                 bbbbuuuunnnnddddlllliiiinnnngggg but now long option names override option bundles.
                 In the above example, ----vvvvaaaaxxxx would be interpreted as the option
                 "vax", not the bundle "v", "a", "x".

                 Note: resetting bbbbuuuunnnnddddlllliiiinnnngggg____oooovvvveeeerrrrrrrriiiiddddeeee also resets bbbbuuuunnnnddddlllliiiinnnngggg.



                                                                        PPPPaaaaggggeeee 8888






GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))                                                GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))



                 NNNNooootttteeee:::: Using option bundling can easily lead to unexpected
                 results, especially when mixing long options and bundles.
                 Caveat emptor.

     ignore_case  (default: set)
                 If set, case is ignored when matching options.

                 Note: resetting iiiiggggnnnnoooorrrreeee____ccccaaaasssseeee also resets iiiiggggnnnnoooorrrreeee____ccccaaaasssseeee____aaaallllwwwwaaaayyyyssss.

     ignore_case_always (default: reset)
                 When bundling is in effect, case is ignored on single-
                 character options also.

                 Note: resetting iiiiggggnnnnoooorrrreeee____ccccaaaasssseeee____aaaallllwwwwaaaayyyyssss also resets iiiiggggnnnnoooorrrreeee____ccccaaaasssseeee.

     pass_through (default: reset)
                 Unknown options are passed through in @ARGV instead of being
                 flagged as errors. This makes it possible to write wrapper
                 scripts that process only part of the user supplied options,
                 and passes the remaining options to some other program.

                 This can be very confusing, especially when ppppeeeerrrrmmmmuuuutttteeee is also
                 set.

     prefix      The string that starts options. See also pppprrrreeeeffffiiiixxxx____ppppaaaatttttttteeeerrrrnnnn.

     prefix_pattern
                 A Perl pattern that identifies the strings that introduce
                 options.  Default is (--|-|\+) unless environment variable
                 POSIXLY_CORRECT has been set, in which case it is (--|-).

     debug (default: reset)
                 Enable copious debugging output.

OOOOTTTTHHHHEEEERRRR UUUUSSSSEEEEFFFFUUUULLLL VVVVAAAARRRRIIIIAAAABBBBLLLLEEEESSSS
     $Getopt::Long::VERSION
                 The version number of this Getopt::Long implementation in the
                 format major.minor. This can be used to have Exporter check
                 the version, e.g.

                     use Getopt::Long 3.00;

                 You can inspect $Getopt::Long::major_version and
                 $Getopt::Long::minor_version for the individual components.

     $Getopt::Long::error
                 Internal error flag. May be incremented from a call-back
                 routine to cause options parsing to fail.







                                                                        PPPPaaaaggggeeee 9999






GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))                                                GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))



AUTHOR
     Johan Vromans <[e-mail]>

CCCCOOOOPPPPYYYYRRRRIIIIGGGGHHHHTTTT AAAANNNNDDDD DDDDIIIISSSSCCCCLLLLAAAAIIIIMMMMEEEERRRR
     This program is Copyright 1990,1999 by Johan Vromans.  This program is
     free software; you can redistribute it and/or modify it under the terms
     of the GNU General Public License as published by the Free Software
     Foundation; either version 2 of the License, or (at your option) any
     later version.

     This program is distributed in the hope that it will be useful, but
     WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
     Public License for more details.

     If you do not have a copy of the GNU General Public License write to the
     Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.






































                                                                       PPPPaaaaggggeeee 11110000






GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))                                                GGGGeeeettttoooopppptttt::::::::LLLLoooonnnngggg((((3333))))























































                                                                       PPPPaaaaggggeeee 11111111